home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1992 …SCII & the Runetime Code / ADC Developer CD (1992-07) (''Butch ASCII And The Runtime Code'')_iso / Dev.CD 199207.iso / Development Platforms / HyperCard Related / XCMDs & XFCNs / Help XFCN / docs / about help next >
Encoding:
Text File  |  1991-03-19  |  3.0 KB  |  88 lines  |  [TEXT/MPS ]
  1. Read the "Help XFCN RN x.x" release notes first.
  2.  
  3. The following is an overview of the help XFCN code operation.
  4. See the source files for more detailed information.
  5.  
  6.     12-03-90 1.0d3 JRP    initial creation of these notes
  7.     
  8.     John R. Powers, III
  9.     GFX Group
  10.     Instructional Products Department
  11.     Apple Computer, Inc.
  12.     408-974-9851 (Apple office)
  13.     408-395-1158 (Home office)
  14.     AppleLink: JohnPowers
  15.     
  16. Files
  17.  
  18.         buildHelp        sets up and executes the make
  19.         help.c            This source file
  20.         help.r            Rez source
  21.         gfun.c            source for using HyperCard globals
  22.         gfun.pro        prototypes for gfun.c
  23.         trap.c            source for using Gestalt
  24.         trap.pro        prototypes for trap.c
  25.         vers.h            header with version information
  26.         makefileHelp    make file
  27.         helpLab            HyperCard stack for testing
  28.  
  29. buildHelp sets up the MPW shell variables used in
  30. makefileHelp and executes the make.  To build the
  31. XFCN, do the following:
  32.  
  33. (1) Setup the folder and files as described below.
  34. (2) Execute "buildHelp <path to Help folder>" from the MPW worksheet.
  35.  
  36. The entrypoint is in help.c.  This file contains the
  37. functions that are specific to help and some general
  38. utilities for interfacing with HyperCard.
  39.  
  40. gfun.c contains a set of utility functions for using
  41. HyperCard globals.  These functions do the callbacks
  42. to HyperCard and the translation of the handle to
  43. a global-useable form.
  44.  
  45. trap.c is a library of functions for using Gestalt.
  46. It contains the 3.1 (not 3.2) method to test for
  47. Gestalt as well as application-specific tests (like
  48. testing for the Help Manager.)  This file is expanded
  49. as we add more Gestalt tests.
  50.  
  51. Operation Overview
  52.  
  53.     All strings are stored in a STR# named "help".  Since
  54.     we want to use the GetIndString, we first lookup the
  55.     STR# by name to get its resource number.  The resource
  56.     number, strResId, is then used throughout the XFCN to
  57.     reference the STR# resource.
  58.     
  59.     Test for version and help commands first.  All other
  60.     commands require the Help Manager.  If it is not a
  61.     version or help command, we make sure the Help Manager
  62.     is present.
  63.     
  64.     Make note of the current state of help (helpEnabled)
  65.     so that we can restore that state when we exit the XFCN.
  66.     If needed, we enable help.
  67.     
  68.     Pick off the parameters following the command and convert
  69.     them to a form that can be used by the Help Manager.  The
  70.     fourth and last parameter is the optional alternativeRect
  71.     or hotRect.
  72.     
  73. Use of alternativeRect/hotRect
  74.  
  75.     An area on the heap is saved to store the alternativeRect
  76.     (also called hotRect).  The handle to this area is stored
  77.     as a HyperCard Global whose name is stored in globalNamePstr.
  78.     When the XFCN is called, a test is made to see if the
  79.     global has anything in it.  If it does, then that is the
  80.     handle used for storing the hotRect.  If it doesn't, then
  81.     a new handle is created and stored in the global.
  82.     
  83.     If the hotRect parameter is present, it is converted from
  84.     a comma-delimited string to a Rect.  The rect is stored on
  85.     the heap, referenced by the handle stored in the HyperCard
  86.     global.  The handle is locked and dereferenced to a pointer.
  87.     The pointer is passed to the Help Manager.
  88.